<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Introspecting function templates technique</title>
<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="Chapter 1. The Type Traits Introspection Library">
<link rel="up" href="../index.html" title="Chapter 1. The Type Traits Introspection Library">
<link rel="prev" href="tti_detail_has_template/tti_detail_has_template_metafunction.html" title="Using the has_template_(xxx) metafunction">
<link rel="next" href="tti_detail_has_member_data.html" title="Introspecting member data">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
<td align="center"><a href="../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="tti_detail_has_template/tti_detail_has_template_metafunction.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tti_detail_has_member_data.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="the_type_traits_introspection_library.tti_function_templates"></a><a class="link" href="tti_function_templates.html" title="Introspecting function templates technique">Introspecting
    function templates technique</a>
</h2></div></div></div>
<p>
      <a name="sectti_function_templates"></a>Function templates, like functions,
      can be entities within a user-defined type. Just as functions within a user-defined
      type can be member functions or static member functions, function templates
      within a user-defined type can be member function templates or static member
      function templates. In this respect function templates are related to functions.
      Function templates represent a family of possible functions. In this respect
      they are similar to class templates, which represent a family of possible class
      types.
    </p>
<p>
      The technique for introspecting class templates in the TTI library is taken
      from the implementation of the technique in the Boost MPL library. In the case
      of <code class="computeroutput"><span class="identifier">BOOST_TTI_HAS_TEMPLATE</span></code> using
      the template type parameters form it directly uses the Boost MPL library functionality
      while in the case of <code class="computeroutput"><span class="identifier">BOOST_TTI_HAS_TEMPLATE</span></code>
      using the specific form it replicates much of the technique in the Boost MPL
      library. Either technique for introspecting class templates depends directly
      on the fact that in C++ we can pass a template as a parameter to another template
      using what is called a "template template" parameter type.
    </p>
<p>
      One obvious thing about a template template parameter type is that it is a
      class template. The fact that we can pass class templates as a template parameter
      but not function templates as a template parameter is the major factor why
      there is no equivalent method for introspecting a function template signature
      at compile time as there is for introspecting class templates signature.
    </p>
<h4>
<a name="the_type_traits_introspection_library.tti_function_templates.h0"></a>
      <span class="phrase"><a name="the_type_traits_introspection_library.tti_function_templates.introspection_using_an_instantiated_function_template"></a></span><a class="link" href="tti_function_templates.html#the_type_traits_introspection_library.tti_function_templates.introspection_using_an_instantiated_function_template">Introspection
      using an instantiated function template</a>
    </h4>
<p>
      Although there is no way to introspect for a function template signature in
      TTI, there is an alternate way of introspecting a function template. It is
      possible to check whether some particular <span class="bold"><strong>instantiation</strong></span>
      of a nested function template exists at compile-time without generating a compiler
      error, as long as all the lower level indidual types in that instantiation
      exist at the time introspection of a function template occurs. In plainer C++
      terms we call the instantiation of a function template "calling ( or invoking
      ) the function template". Although checking whether some particular instantiation
      of a nested function template exists at compile-time does not prove that the
      nested function template itself has a particular signature, since the instantiation
      itself may fail even when the nested function template does exist, it provides
      a viable way of introspecting function templates because the vast majority
      of function templates are designed to accept any type(s) and avoid compile
      time failure. Also when we introspect using a function template instantiation
      for a nested function template we are replicating how function templates are
      actually used in C++.
    </p>
<p>
      To see how this works in general in the TTI library I will give an example
      of a nested function template in a user-defined type.
    </p>
<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">AType</span>
  <span class="special">{</span>
  <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">X</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">Y</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">Z</span><span class="special">&gt;</span> <span class="keyword">double</span> <span class="identifier">AFuncTemplate</span><span class="special">(</span><span class="identifier">X</span> <span class="identifier">x</span><span class="special">,</span><span class="identifier">Y</span> <span class="special">*</span> <span class="identifier">y</span><span class="special">,</span><span class="identifier">Z</span> <span class="special">&amp;</span> <span class="identifier">z</span><span class="special">)</span>
    <span class="special">{</span> <span class="special">...</span><span class="identifier">some</span> <span class="identifier">code</span> <span class="keyword">using</span> <span class="identifier">x</span><span class="special">,</span><span class="identifier">y</span><span class="special">,</span><span class="identifier">z</span><span class="special">;</span> <span class="keyword">return</span> <span class="number">0.0</span><span class="special">;</span> <span class="special">}</span>
  <span class="special">};</span>
</pre>
<p>
      The code shows a member function template within a user-defined struct called
      <code class="computeroutput"><span class="identifier">AType</span></code>. Ideally what we would
      like to do is to be able to verify that the function template signature of
      <code class="computeroutput"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">X</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">Y</span><span class="special">,</span><span class="keyword">class</span> <span class="identifier">Z</span><span class="special">&gt;</span>
      <span class="keyword">double</span> <span class="identifier">AFuncTemplate</span><span class="special">(</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">Y</span> <span class="special">*,</span><span class="identifier">Z</span>
      <span class="special">&amp;)</span></code> exists within the <code class="computeroutput"><span class="identifier">AType</span></code> type, but we can not do that in TTI.
      If we were to call <code class="computeroutput"><span class="identifier">AFuncTemplate</span></code>
      from within some functionality within the <code class="computeroutput"><span class="identifier">AType</span></code>
      type, we would substitute some arguments for <code class="computeroutput"><span class="identifier">X</span><span class="special">,</span><span class="identifier">Y</span> <span class="special">*,</span><span class="identifier">Z</span> <span class="special">&amp;</span></code> and
      the C++ compiler would be able to figure out the types for X, Y, and Z and
      create a function to be called.
    </p>
<p>
      If we look at this in terms of compile time programming ( aka template metaprogramming
      ) what we are really interested in is whether there is a function template
      called <code class="computeroutput"><span class="identifier">AFuncTemplate</span></code> within
      a type called <code class="computeroutput"><span class="identifier">AType</span></code> which can
      be invoked with the X, Y, and Z types as some set of types which are equivalent
      to calling <code class="computeroutput"><span class="identifier">AFuncTemplate</span></code> with
      some set of arguments. Let's suppose we want to call <code class="computeroutput"><span class="identifier">AFuncTemplate</span></code>
      with an <code class="computeroutput"><span class="keyword">int</span></code> value as the first
      argument, <code class="computeroutput"><span class="keyword">long</span> <span class="special">*</span></code>
      as the second argument, and a <code class="computeroutput"><span class="keyword">bool</span> <span class="special">&amp;</span></code> as the third argument. In TTI introspection
      terms for a function template what we therefore are going to do is to check
      if we can instantiate the function template as:
    </p>
<pre class="programlisting"><span class="keyword">double</span> <span class="identifier">AFuncTemplate</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span><span class="keyword">long</span><span class="special">,</span><span class="keyword">bool</span><span class="special">&gt;(</span><span class="keyword">int</span><span class="special">,</span><span class="keyword">long</span> <span class="special">*,</span><span class="keyword">bool</span> <span class="special">&amp;)</span>
</pre>
<p>
      This is the form of a single possible instantiation of function template <code class="computeroutput"><span class="identifier">AFuncTemplate</span></code>. When it is subsequently explained
      how to use an instantiation of a function template to check if an inner function
      template exists, this is what we mean. The instantiation itself does not exist
      when we introspect a function template but all the parts of our instantiation
      signature are used in the process of introspection. It should be realized that
      we could use any combination of valid types or values to create our theoretical
      instantiation of a given function template, as long as those type and/or values
      produces a valid callable function which does not contain compile time errors.
    </p>
<p>
      The actual types and/or values we use in an instantiation of a function template
      we introspect must be declared when we do the introspection. For built-in types
      this is always the case. If we use instead, for whatever reason, a user-defined
      type in a given instantiation, that type must be declared when we invoke the
      metafunction which does the introspection.
    </p>
<p>
      Further areas of the documentation will explain in its place how we use an
      instantiation of a function template to introspect respectively a member function
      template, a static member function template, or any inner function template.
      The technique we use is very similar to the way we introspect any nested entity,
      but instead of looking for a signature that declares that nested entity, with
      function templates we look for a signature representing some instantiation
      of the function template.
    </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2011-2013 Tropic Software
      East Inc<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="tti_detail_has_template/tti_detail_has_template_metafunction.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tti_detail_has_member_data.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
